home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 July / Macworld (1999-07).dmg / Shareware World / Info / For Developers / Mops 3.4.sea / Quick Edit ƒ / Subject Glossary / Events < prev    next >
Text File  |  1992-11-29  |  10KB  |  264 lines
  1. MOPS WINDOWS and EVENTS
  2.  
  3. ********* IMPORTANT OBJECTS, VECTS, and VALUEs
  4.  
  5. fevent      class event
  6. themouse    class mouse
  7. mbaddr        class dicaddr   will be sent click: messages by fevent
  8.  
  9. wnd            A value, contains the wptr of the window we are looking at.
  10.             This will be set by a call to FindWindow in the mousedown
  11.             handler or by FrontWindow in the key event handler.
  12.             Note that fevent will send messages to this window.
  13.  
  14. ActW         A value, identifies any active active Mops window which should be idled
  15.             Will be set to zero if we have, say, a dialog as the front window,
  16.             but NOT if we're switched into the background.
  17.  
  18. SaveActW     A value, Saves Actw over suspend/resume.
  19.  
  20.  
  21.  
  22. ********** Mops Event Loop Explained
  23.  
  24. Normally, Mops should be in a loop something like the following if you
  25. want your program to repsond to keyboard input:
  26.  
  27.     BEGIN
  28.         key        \ key polls events and performs all default behavior
  29.                 \ while waiting for a key to be pressed
  30.         actW
  31.             IF
  32.                     key: actW    \ pass keystroke to our window
  33.             ELSE
  34.                     drop        \ not our window, so drop the keystroke
  35.             THEN
  36.     AGAIN ;
  37.  
  38. But be careful.  Once you have put Mops in the above loop you won't be
  39. able to type commands from the console window.  Class window, which is
  40. the class of fwind (the console) responds to key: messages by doing
  41. nothing.  One solution would be to set a menu handler to grab Mops's
  42. attention by executing SP!.  Or one could use Quick Edit, if you are
  43. using System 7, to communicate with Mops even while it is in the
  44. above loop.
  45.  
  46. From Mike Hore:   
  47. actW is the value that "officially" holds the addr of the frontmost Mops
  48. window, or is zero if there isn't one.  wnd is just temporary storage.  It's
  49. normally the same as actW, but needn't be.  If, say, your application has a
  50. "normal" window and also another window with status information or something,
  51. you might not want the status window to become active even if it's clicked on. 
  52. But wnd holds the addr of any window clicked on, no matter what.  The above
  53. loop will work even if you have no windows open at all. 
  54.  
  55.  
  56. key is merely doing the following:
  57.  
  58. key: fevent  ( c mods) drop $ ff and  ( c' )
  59.  
  60.  
  61. fevent is an instance of the EVENT class which is basically an X-ARRAY,
  62. with some additional data and methods, which when sent the key: message
  63. will get the next event from the Mac system and execute the appropriate
  64. handler in fevent.  fevent is loaded with 23 event handlers (see file
  65. Objinit) as follows:
  66.  
  67. event#        fevent            Mac Toolbox        Late Bound
  68.             handler            equate            Messages to wnd
  69.                                             or ActW or mbaddr
  70. ------        ---------        -----------        -----------------
  71.  
  72.  
  73. 0            null-evt        nullEvt            idle: ActW
  74. 1            mouse-evt        mButDwnEvt        content: wnd
  75.                                             click: mbaddr
  76.                                             drag: wnd
  77.                                             grow: wnd
  78.                                             close: wnd
  79.                                             zoom: wnd
  80. 2            null-evt        mButUpEvt
  81. 3            key-evt            keyDwnEvt        key: mbaddr
  82. 4            null-evt         keyUpEvt 
  83. 5            key-evt            autoKeyEvt
  84. 6            upd-evt            updatEvt        draw: wnd
  85. 7            disk-evt        diskInsertEvt
  86. 8            actv-evt        activateEvt        enable: wnd
  87.                                             disable: wnd
  88. 9            null-evt        not used
  89. 10            null-evt        networkEvt
  90. 11            null-evt        ioDrvrEvt
  91. 12            null-evt        app1Evt
  92. 13            null-evt        app2Evt
  93. 14            null-evt        app3Evt
  94. 15            null-evt        osEvt (was app4Evt)  see IM-VI 5-19
  95.                                             enable: wnd
  96.                                             disable: wnd
  97. 16            null-evt        not used
  98. 17            null-evt        not used
  99. 18            null-evt        not used
  100. 19            null-evt        not used
  101. 20            null-evt        not used
  102. 21            null-evt        not used
  103. 22            null-evt        not used
  104. 23            HL-evt            kHighLevelEvent  see IM-VI 5-21
  105.  
  106.  
  107. It is easy to change any of these event handlers at any time, since we can
  108. just define a word, tick its cfa, and store into fevent:
  109.  
  110.     ' new-evt-handler  4 to: fevent        \ set a handler for key up events
  111.  
  112. The event handlers in fevent will send late bound messages to wnd.
  113.  
  114.  
  115. FEVENT ACTION HANDLERS
  116.  
  117. -MODELESS    --
  118.     Sets normal event handling - no modeless dialogs, by storing the appropriate 23 
  119.     event handlers in the event object fevent.  
  120. ACTV-EVT    -- false
  121.     Handles activate and deactivate events by sending a late bound 
  122.     enable:and disable: messages to the current window (but only if it is an 
  123.     application window).  
  124. DISK-EVT    -- false    Handles a disk insert event.
  125. HL-EVT    -- falseHandles High-level events.  Several vects are involved.
  126. KEY-EVT    -- keywd modswd T  |  -- F
  127.     Gets key value if true.  Handles command-key menu actions.  Does not 
  128.     handle "normal" key actions, that is up to your code.  
  129. MOUSE-EVT    -- false    Handles mouse events.
  130. NULL-EVT    -- false    
  131.     Will send late bound idle: to the actW, if it is non-zero.
  132. OS-EVT    -- false    Handles operating system events by calling various vects.
  133. UPD-EVT    -- false    
  134.     Handles update events by sending a late bound draw: message to the 
  135.     current window (but only if it is an application window).  
  136.  
  137.  
  138.  
  139. APPWIND?    -- b
  140.     True if this is an application window.  This check is necessary for 
  141.     non-multifinder systems while calling WaitNextEvent.  
  142. KEY    -- c
  143.     A system vector.  The action of key is normally (key).  (key!) is used 
  144.     to set the default action for key.  
  145. (KEY!)    --
  146.     Sets the default action for vect key by storing the cfa of (key) in it.
  147. (KEY)    -- c
  148.     The default action for key.  c is the character corresponding to the key 
  149.     that was pressed.  : (key) key: fevent drop $ FF and ; 
  150. (PAUSE)    --    Our standard action for the vect pause.
  151. ?EVENT    eventMask -- b
  152.     Calls the Toolbox Event Manager routine EventAvail to test for the 
  153.     event(s) specified by eventMask.  If an event is available, leaves a 
  154.     true flag; otherwise, leaves a false flag.  
  155. ?PAUSE    --    
  156. ?TERMINAL    --
  157.     Performs a 40 ?Event.  This word is used in class Mouse, and in the 
  158.     utility word ?pause to test for a keyboard event.  
  159.  
  160.  
  161. APPLE EVENTS
  162.  
  163. (AEErr)    err# --
  164.     Default for error returns from AppleEvent handlers, i.e.  this is the 
  165.     action for AEErrorVec.  
  166. AEErrorVec    --
  167.     A vect.  Called when an AppleEvent handler returns.  Default is (AEerr).
  168. AEhandler    ^AE ^AEReply RefCon --
  169.     Put at the start of an AppleEvent handler proc.  Pops the parms into the 
  170.     appropriate locations.  
  171. AppleEvents?    -- b
  172.     A value.  Set True by the startup code if AppleEvents are available.
  173. ?RTNAEPMISSED    w:xx rc -- w:rc'
  174.     This can be called after calling GotParms? to convert the return code 
  175.     from that word to the appropriate return code to return to the caller of 
  176.     the handler.  If GotParms? returns false, that means we missed a parm, 
  177.     so we return -1715.  If GotParms? returned anything non-zero, that means 
  178.     we got all the parms, so we return zero.  
  179. doAEhandler    ^AE ^AEReply RefCon --
  180.     Called from AEhandler to set things up at the start of a handler.
  181. FAE    -- ^AE    A value used to handle AppleEents.
  182. HLEventVEC    --
  183.     A vect.  Called for generic high-level events.  Default is vfalse.
  184.  
  185.  
  186. MISCELLANEOUS
  187.  
  188. #docsToOpen    -- n    A value.
  189. BECOME    --  : word
  190.     BECOME allows restarting at a given word, with all stacks empty.  This 
  191.     is necessary in menu handlers and other areas that could create 
  192.     indefinite nesting situations.  
  193. CvtClip    --    A vect.  Called for clip conversion.
  194. DBLTICKS    -- n
  195.     Returns the double-click interval in ticks via the Mac global variable 
  196.     DoubleTime.  
  197. DESK    --    Desktop click handler - do nothing.
  198. FIND-WINDOW    Tpoint  --  region  ^window
  199.     Calls the Window Manager routine FindWindow to find the window in which 
  200.     a mouse-down event occurred at Tpoint, a Toolbox point in global 
  201.     coordinates.  Leaves the region of the window in which the mouse-down 
  202.     occurred and ^window, the pointer to the window object's private data.  
  203. GOTPARMS?    -- rc
  204.     This can be called at the end of a handler, to check if we got all the 
  205.     parameters.  
  206. MouseMoved    --    A vect.  Called for mouse moved.
  207. NEXTEVENT    ^event mask -- b
  208.     We call WaitNextEvent if it's available, otherwise GetNextEvent.
  209. NEXT_TASK    --
  210.     A vect.  If multitasking is installed, this will be redirected to do a 
  211.     task switch.  
  212. OpenAppVec    -- code True  |  -- False
  213.     As set up in Mops, OpenAppVec simply returns False and does nothing 
  214.     else.  
  215. OpenDocHandler    ?
  216.     Normal :PROC entry sequence to set up the Mops addressing environment
  217. OpenDocVec    -- code True  |  -- False
  218.     OpenDocVec finds the number of files in the given list of files, and 
  219.     puts the number in the value #DocsToOpen.  It then handles each file in 
  220.     the given list fFcb, then calling the sufficient for your appropriately.  
  221. OpenMopsDic    ?    OpenMopsDic is the default for OpenDocVec.
  222. PAUSE    --
  223.     A system vector, normally contains (pause), defined in file Frontend.  
  224.     PAUSE should be called at strategic intervals in all applications, 
  225.     unless Key is being called frequently.  Pause normally calls next: 
  226.     fEvent which allows a task switch to be done under MultiFinder, and 
  227.     which also handles any pending events for this task, such as window 
  228.     updates.  Remember to disable any menus etc.  that you don't want to 
  229.     execute in this situation! Unexpected re-entrancy is a good way to bomb! 
  230. PrintDocHandler    ?
  231.     Normal :PROC entry sequence to set up the Mops addressing environment
  232. QuitAppHandler    ?
  233.     Normal :PROC entry sequence to set up the Mops addressing environment
  234. QuitAppVec    -- code True  |  -- False
  235.     The current setting for QuitAppVec is simply to call BYE.  Your 
  236.     application will probably want to do something a bit more intelligent.  
  237. Read1DocVec    -- code True  |  -- False
  238.     As set up, Read1DocVec assumes the file is a Mops dictionary.  
  239.     Read1DocVec must point to a routine which will read the file designated 
  240.     by the file object fFcb, close it, and return a result on the stack.  
  241.     True indicates the OpenDocVec loop can continue.  False means the loop 
  242.     must terminate.  You could return False, for example, on an error, or 
  243.     simply if your application can't accept more than one document open at a 
  244.     time.  
  245. RESUME?    -- b    A value.  True if we've just received a Resume event.
  246. ResumeVec    --    A vect.  Called for resume.
  247. SaveActW    -- wptr    Saves actW over Suspend-Resume.
  248. SLEEPTICKS    -- n
  249.     A value.  Used in calls to WaitNextEvent.  Default is 20 as set by file 
  250.     Frontend.  
  251. STILLDOWN?    -- b
  252.     A direct call to StillDown.  Returns true if mouse button is still down.
  253. SUSPEND?    -- b
  254.     A value.  True if we've just received a Suspend event.
  255. SuspendVec    --    A vect.  Called for suspend.
  256. SYS    wptr --    System  click handler, a direct call to SystemClick.
  257. THEDLG    -- addr    A variable.
  258. THEPOINT    -- addr    A variable.
  259. WAITCLICK    --    Waits until a mouse click or key event.
  260. WHRFEV    -- point    Will become  where: fEvent .
  261. WNEavail?    -- b
  262.     A value.  Set True by the startup code if the WaitNextEvent trap is 
  263.     available in the System being used.  
  264.